-- Plugins

Monday, September 23, 2024

6:24 AM

OneNote can execute plugins that can process a page or hierarchy using a program that you write. This provides a simple way to experiment with page adjustments.

 

⚠

NOTICE

This is an experimental feature. There is no guarantee, warranty, or promise that you won't screw it up and loose data! It's in your hands and if you mess up the XML and cause data loss, that's entirely on you. You've been warned.

 

When writing a PowerShell plugin, specify powershell or pwsh as the Command and enter and use the Arguments line to specify the -file argument pointing to your script as shown here.

 

The User Arguments field is used to pass additional arguments to your script or program. The first argument will always be the path of the incoming XML. User arguments will be appended to that. Be sure to quote strings if they might contain spaces.

 

 

The workflow is very simple.

 

  1. Create a plugin program that accepts one command line argument; the argument will specify the path to a file containing the page XML.
  2. Run the Plugin command, specifying the path to the program and any other arguments.
  3. The plugin must complete within 20 seconds or it will timeout and be aborted.
  4. The plugin must write any desired changes back to the file path it was given.
  5. If the plugin completes and has made changes to the XML file on disk then OneMore will update the current page with your updated XML from the file;
  6. If the plugin completes and has not made changes to the file then no changes are made to the current page.
  7. If you chose to create a new page then it will be created regardless of whether the plugin updated the XML file.

 

Any output that your plugin writes to stdout will be captured in the OneMore log file.

 

Note, if you run the plugin and a Web browser is invoked (IE) showing the XML file contents then you probably forgot to specify the right arguments to powershell.exe or python.exe.

 

You can use the special keyword $name in the Page Name field. This will be replaced with the name of the current page when you invoke the plugin from the Favorites menu or choose it from the drop-down list. For example, if you're on page "Forecasting" and the Page Name is set to "Quarterly $name" then the created page when it will be named "Quarterly Forecasting"

 

The default timeout - time allotted in which a plugin must complete - is 15 seconds. You can change that by entering the number of seconds into the Timeout field. If set to zero then the timeout is set to one hour.

 

The following environment variables are set when calling a plugin.

 

  • PLUGIN_ASCHILD - set to true when the Create as child option is checked
  • PLUGIN_CREATE - set to true when the Create as new page option is checked
  • PLUGIN_PAGENAME - specifies the name of the page to create or update
  • PLUGIN_SOURCE_PAGEID - the OneNote ID of the source page
  • PLUGIN_SOURCE_SECTIONID - the OneNote ID of the source page's section
  • PLUGIN_SOURCE_NOTEBOOKID - the OneNote ID of the source page's notebook
  • PLUGIN_SOURCE_PAGENAME - the title of the source page
  • PLUGIN_SOURCE_PAGEPATH - the hierarchy path of the source page, including notebook, section, and page name
  • PLUGIN_SOURCE_PAGEURL - the OneNote URL of the source page
  • PLUGIN_SKIPLOCK - set to true when the Skip locked sections option is checked

 

The OneNote page schema is defined in the 0336.OneNoteApplication_2013.xsd file in the References folder of the project repo.

 

 

#omwiki #omcommands

 

© 2020 Steven M Cohn. All rights reserved.

Please consider a sponsorship or one-time donation to support ongoing development

 

Created with OneNote.